home *** CD-ROM | disk | FTP | other *** search
/ Amiga Collections: Franz PD / Franz PD Disk #203 (1992)(Rhein-Sieg-Soft).zip / Franz PD Disk #203 (1992)(Rhein-Sieg-Soft).adf / AK_gen0-Library / Programmers / AK_GEN0-Lib_Reference.doc next >
Text File  |  1992-11-19  |  19KB  |  824 lines
  1.  
  2.    AK_GEN0-Lib_Reference.doc V35.106 , 03 July 1992
  3.  
  4.    (c) 1989-92 by Andreas R. Kleinert
  5.  
  6.    Here is a listing of all the functions in the style of the 'RKM' :
  7.  
  8.    
  9.    IMPORTANT NOTE :
  10.  
  11.    All Parameters are STACK-Parameters, because often there are too many
  12.    parameters, which won't fit all into the registers.
  13.  
  14. -----------------------------------------------------------------------------
  15.  
  16.    NAME
  17.         AK_Screen -- Open a Screen
  18.  
  19.    SYNOPSIS
  20.  
  21.         struct Screen * AK_Screen(long l, long t, long w, long h,
  22.                                   long d, long dp, long bp, long vm,
  23.                                   long ty, struct TextAttr *f,
  24.                                   char *title, struct BitMap *cbm);
  25.  
  26.    FUNCTION
  27.  
  28.         Opens a screen, which has been described by the parameters.
  29.  
  30.    INPUT(S)
  31.  
  32.         l, t, w, h - LeftEdge, TopEgde, Width, Height of struct NewScreen
  33.         d          - Depth of struct NewScreen
  34.         dp, bp     - DetailPen, BlockPen of struct NewScreen
  35.         vm         - ViewModes of struct NewScreen
  36.         ty         - Type of struct NewScreen
  37.         f          - Font of struct NewScreen
  38.         title      - DefaultTitle of struct NewScreen
  39.         cbm        - CustomBitMap of struct NewScreen
  40.  
  41.    RESULT
  42.  
  43.         A pointer to a new opened screen or NULL, if opening failed.
  44.  
  45.    WARNING
  46.  
  47.         Test, if the result was NULL, or not !
  48.  
  49.    BUGS
  50.  
  51.         -
  52.  
  53.    SEE ALSO
  54.  
  55.         AK_Window
  56.  
  57. -----------------------------------------------------------------------------
  58.  
  59.    NAME
  60.         AK_Window -- Open a Window
  61.  
  62.    SYNOPSIS
  63.  
  64.         struct Window * AK_Window(long l, long t, long w, long h, long d,
  65.                                   long b, long idcmp, long flags,
  66.                                   struct Gadget *fg, struct Image *cm,
  67.                                   char *title, struct Screen *screen,
  68.                                   struct BitMap *bm, long minw, long minh,
  69.                                   long maxw, long maxh, long type)
  70.  
  71.    FUNCTION
  72.  
  73.         Opens a window, which has been described by the parameters.
  74.  
  75.    INPUT(S)
  76.  
  77.         l, t, w, h - LeftEdge, TopEgde, Width, Height of struct NewWindow
  78.         d, b       - DetailPen, BlockPen of struct NewWindow
  79.         idcmp      - IDCMPFlags of struct NewWindow
  80.         flags      - Flags of struct NewWindow
  81.         fg         - FirstGadget of struct NewWindow
  82.         cm         - CheckMark of struct NewWindow
  83.         title      - Title of struct NewWindow
  84.         screen     - Screen of struct NewWindow
  85.         bm         - BitMap of struct NewWindow
  86.         minw       - MinWidth of struct NewWindow
  87.         minh       - MinHeight of struct NewWindow
  88.         maxw       - MaxWidth of struct NewWindow
  89.         maxh       - MaxHeight of struct NewWindow
  90.         type       - Type of struct NewWindow
  91.  
  92.    RESULT
  93.  
  94.         A pointer to a new opened window or NULL, if opening failed.
  95.  
  96.    WARNING
  97.  
  98.         Test, if the result was NULL, or not !
  99.    BUGS
  100.  
  101.         -
  102.  
  103.    SEE ALSO
  104.  
  105.         AK_Screen
  106.  
  107. -----------------------------------------------------------------------------
  108.  
  109.    NAME
  110.  
  111.         AK_Menu
  112.  
  113.    SYNOPSIS
  114.  
  115.         struct Menu * AK_Menu(struct Menu *next, long l, long w, long flags,
  116.                               char *name, struct MenuItem *item)
  117.  
  118.    FUNCTION
  119.  
  120.         Allocs and fills out a "Menu"-structure.
  121.  
  122.    INPUT(S)
  123.  
  124.         next       - NextMenu of struct Menu
  125.         l          - LeftEdge of struct Menu
  126.         w          - Width of struct Menu
  127.         flags      - Flags of struct Menu
  128.         name       - MenuName of struct Menu
  129.         item       - FirstItem of struct Menu
  130.  
  131.    RESULT
  132.  
  133.         A pointer to an initialized "Menu"-structure or NULL, if failed.
  134.  
  135.    WARNING
  136.  
  137.         a) First initialize the items in reverse order, then the menus in
  138.            reverse order.
  139.  
  140.         b) Test, if the result was NULL, or not !
  141.  
  142.    BUGS
  143.  
  144.         -
  145.  
  146.    SEE ALSO
  147.  
  148.         AK_MenuItem, AK_SubItem
  149.  
  150. -----------------------------------------------------------------------------
  151.  
  152.    NAME
  153.  
  154.         AK_MenuItem
  155.  
  156.    SYNOPSIS
  157.  
  158.         struct MenuItem * AK_MenuItem(struct MenuItem *next, long t, long w,
  159.                                       long flags, long me, APTR itfi, 
  160.                                       APTR sefi, long scut,
  161.                                       struct MenuItem * subi)
  162.  
  163.    FUNCTION
  164.  
  165.         Allocs and fills out a "MenuItem"-structure.
  166.  
  167.    INPUT(S)
  168.  
  169.         next       - NextMenu of struct MenuItem
  170.         l          - LeftEdge of struct MenuItem
  171.         t          - TopEdge of struct MenuItem
  172.         w          - Width of struct MenuItem
  173.         flags      - Flags of struct MenuItem
  174.         me         - MutualExclude of struct MenuItem
  175.         itfi       - ItemFill of struct MenuItem
  176.         sefi       - SelectFill of struct MenuItem
  177.         scut       - Command of struct MenuItem
  178.         subi       - SubItem of struct MenuItem
  179.  
  180.    RESULT
  181.  
  182.         A pointer to an initialized "MenuItem"-structure or NULL, if failed.
  183.  
  184.    WARNING
  185.  
  186.         a) First initialize the items in reverse order, then the menus in
  187.            reverse order.
  188.  
  189.         b) Test, if the result was NULL, or not !
  190.  
  191.    BUGS
  192.  
  193.         -
  194.  
  195.    SEE ALSO
  196.  
  197.         AK_Menu, AK_SubItem
  198.  
  199. -----------------------------------------------------------------------------
  200.  
  201.    NAME
  202.  
  203.         AK_SubItem
  204.  
  205.    SYNOPSIS
  206.  
  207.         struct MenuItem * AK_SubItem(struct MenuItem *next, long l, long t,
  208.                                      long w, long flags, long me, APTR itfi,
  209.                                      APTR sefi, long scut,
  210.                                      struct MenuItem *subi)
  211.  
  212.    FUNCTION
  213.  
  214.         Allocs and fills out a "MenuItem"-structure (here used for a SubItem).
  215.  
  216.    INPUT(S)
  217.  
  218.         next       - NextMenu of struct MenuItem
  219.         l          - LeftEdge of struct MenuItem
  220.         t          - TopEdge of struct MenuItem
  221.         w          - Width of struct MenuItem
  222.         flags      - Flags of struct MenuItem
  223.         me         - MutualExclude of struct MenuItem
  224.         itfi       - ItemFill of struct MenuItem
  225.         sefi       - SelectFill of struct MenuItem
  226.         scut       - Command of struct MenuItem
  227.         subi       - SubItem of struct MenuItem
  228.  
  229.    RESULT
  230.  
  231.         A pointer to an initialized "MenuItem"-structure or NULL, if failed.
  232.  
  233.    WARNING
  234.  
  235.         a) SubItems have to be initialized before the main MenuItems.
  236.  
  237.         b) Test, if the result was NULL, or not !
  238.  
  239.    BUGS
  240.  
  241.         -
  242.  
  243.    SEE ALSO
  244.  
  245.         AK_Menu, AK_MenuItem
  246.  
  247. -----------------------------------------------------------------------------
  248.  
  249.    NAME
  250.  
  251.         AK_Gadget
  252.  
  253.    SYNOPSIS
  254.  
  255.         struct Gadget * AK_Gadget(struct Gadget *next, long l, long t, long w,
  256.                                   long h, long flags, long act, long type,
  257.                                   APTR gadr, APTR selr, struct IntuiText *text,
  258.                                   APTR sp, long id)
  259.  
  260.    FUNCTION
  261.  
  262.         Allocs and fills out a "Gadget"-structure.
  263.  
  264.    INPUT(S)
  265.  
  266.         next       - NextMenu of struct Gadget
  267.         l          - LeftEdge of struct Gadget
  268.         t          - TopEdge of struct Gadget
  269.         w          - Width of struct Gadget
  270.         h          - Height of struct Gadget
  271.         flags      - Flags of struct Gadget
  272.         act        - Activation of struct Gadget
  273.         type       - GadgetType of struct Gadget
  274.         gadr       - GadgetRender of struct Gadget
  275.         selr       - SelectRender of struct Gadget
  276.         text       - GadgetText of struct Gadget
  277.         sp         - SpecialInfo of struct Gadget
  278.         id         - GadgetID of struct Gadget
  279.  
  280.    RESULT
  281.  
  282.         A pointer to an initialized "MenuItem"-structure or NULL, if failed.
  283.  
  284.    WARNING
  285.  
  286.         a) Values for GadgetRender, SelectRender, GadgetText, SpecialInfo
  287.            have to be initialized before.
  288.  
  289.         b) Test, if the result was NULL, or not !
  290.  
  291.    BUGS
  292.  
  293.         -
  294.  
  295.    SEE ALSO
  296.  
  297.         AK_Window, AK_Border, AK_IText, AK_StringInfo
  298.  
  299. -----------------------------------------------------------------------------
  300.  
  301.    NAME
  302.  
  303.         AK_StringInfo
  304.  
  305.    SYNOPSIS
  306.  
  307.         struct StringInfo * AK_StringInfo(long groesse, long maximum, 
  308.                                           struct KeyMap *km)
  309.  
  310.    FUNCTION
  311.  
  312.         Allocs and fills out a "StringInfo"-structure, which is perhaps later
  313.         used with "AK_Gadget".
  314.  
  315.    INPUT(S)
  316.  
  317.         groesse    - Size of the Buffer and the Undo-Buffer used by the
  318.                      StringGadget
  319.         maximum    - MaxChars of struct StringInfo
  320.         km         - AltKeyMap of struct StringInfo (normally NULL)
  321.  
  322.    RESULT
  323.  
  324.         A pointer to an initialized "StringInfo"-structure or NULL, if failed.
  325.  
  326.    WARNING
  327.  
  328.         a) The memory with the size "groesse" has to be given free with
  329.            FreeMem later for two times :
  330.            1. StringInfo->Buffer
  331.            2. StringInfo->UndoBuffer
  332.  
  333.         b) Test, if the result was NULL, or not !
  334.  
  335.    BUGS
  336.  
  337.         -
  338.  
  339.    SEE ALSO
  340.  
  341.         AK_Gadget
  342.  
  343. -----------------------------------------------------------------------------
  344.  
  345.    NAME
  346.  
  347.         AK_Border
  348.  
  349.    SYNOPSIS
  350.  
  351.         struct Border * AK_Border(long l, long t, long f, long b, long d,
  352.                                   long c, WORD *xy, struct Border *next)
  353.  
  354.    FUNCTION
  355.  
  356.         Allocs and fills out a "Border"-structure, which is perhaps later
  357.         used with "AK_Gadget", "AK_MenuItem", "AK_SubItem" or whereever else.
  358.  
  359.    INPUT(S)
  360.  
  361.         l          - LeftEdge of struct Border
  362.         t          - TopEdge of struct Border
  363.         f          - FrontPen of struct Border
  364.         b          - BackPen of struct Border
  365.         d          - DrawMode of struct Border
  366.         c          - Count of struct Border
  367.         xy         - XY of struct Border
  368.         next       - NextBorder of struct Border
  369.  
  370.    RESULT
  371.  
  372.         A pointer to an initialized "Border"-structure or NULL, if failed.
  373.  
  374.    WARNING
  375.  
  376.         Test, if the result was NULL, or not !
  377.  
  378.    BUGS
  379.  
  380.         -
  381.  
  382.    SEE ALSO
  383.  
  384.         AK_Gadget, AK_MenuItem, AK_SubItem, ...
  385.  
  386. -----------------------------------------------------------------------------
  387.  
  388.    NAME
  389.  
  390.         AK_IText
  391.  
  392.    SYNOPSIS
  393.  
  394.         struct IntuiText * AK_IText(long f, long b, long d, long l, long t,
  395.                                     struct TextAttr *font, char *text,
  396.                                     struct IntuiText *next)
  397.  
  398.    FUNCTION
  399.  
  400.         Allocs and fills out a "IntuiText"-structure, which is perhaps later
  401.         used with "AK_Gadget", "AK_MenuItem", "AK_SubItem" or whereever else.
  402.  
  403.    INPUT(S)
  404.  
  405.         f          - FrontPen of struct IntuiText
  406.         b          - BackPen of struct IntuiText
  407.         d          - DrawMode of struct IntuiText
  408.         l          - LeftEdge of struct IntuiText
  409.         t          - TopEdge of struct IntuiText
  410.         font       - ITextFont struct IntuiText
  411.         text       - IText of struct IntuiText
  412.         next       - NextText of struct Border
  413.  
  414.    RESULT
  415.  
  416.         A pointer to an initialized "IntuiText"-structure or NULL, if failed.
  417.  
  418.    WARNING
  419.  
  420.         Test, if the result was NULL, or not !
  421.  
  422.    BUGS
  423.  
  424.         -
  425.  
  426.    SEE ALSO
  427.  
  428.         AK_Gadget, AK_MenuItem, AK_SubItem, ...
  429.  
  430. -----------------------------------------------------------------------------
  431.  
  432.    NAME
  433.  
  434.         AK_GfxPrint
  435.  
  436.    SYNOPSIS
  437.  
  438.         void AK_GfxPrint(struct Window *w, char *text, long x, long y)
  439.  
  440.    FUNCTION
  441.  
  442.         Prints out a text under use of the "graphics.library" functions
  443.         "Move" and "Text".
  444.  
  445.    INPUT(S)
  446.  
  447.         w          - a valid pointer to a window, as returned by AK_Window
  448.         text       - a pointer to a null-terminated string
  449.         x          - x-position for the text
  450.         y          - y-position for the text
  451.  
  452.    RESULT
  453.  
  454.         -
  455.  
  456.    WARNING
  457.  
  458.         -
  459.  
  460.    BUGS
  461.  
  462.         -
  463.  
  464.    SEE ALSO
  465.  
  466.         AK_IntuiPrint
  467.         SetAPen, SetBPen (in "graphics.library")
  468.  
  469. -----------------------------------------------------------------------------
  470.  
  471.    NAME
  472.  
  473.         AK_IntuiPrint
  474.  
  475.    SYNOPSIS
  476.  
  477.         void AK_IntuiPrint(struct Window *w, char *text, long x, long y);
  478.  
  479.    FUNCTION
  480.  
  481.         Prints out a text under use of the "intuition.library" function
  482.         "PrintIText".
  483.  
  484.         w          - a valid pointer to a window, as returned by AK_Window
  485.         text       - a pointer to a null-terminated string
  486.         x          - x-position for the text
  487.         y          - y-position for the text
  488.  
  489.    RESULT
  490.  
  491.         -
  492.  
  493.    WARNING
  494.  
  495.         -
  496.  
  497.    BUGS
  498.  
  499.         -
  500.  
  501.    SEE ALSO
  502.  
  503.         AK_GfxPrint
  504.         SetAPen, SetBPen (in "graphics.library")
  505.  
  506. -----------------------------------------------------------------------------
  507.  
  508.    NAME
  509.  
  510.         AK_RefreshDisp
  511.  
  512.    SYNOPSIS
  513.  
  514.         void AK_RefreshDisp(struct Screen *sc, struct Window *w)
  515.  
  516.    FUNCTION
  517.  
  518.         Cleans the Display under use of the follwing functions out of
  519.         "intuition.library" and "graphics.library" :
  520.         "SetRast()"            (Window/Screen)
  521.         "RefreshWindowFrame()" (Window)
  522.         "RefreshGadgets()"     (Window)
  523.  
  524.    INPUT(S)
  525.  
  526.         sc         - a valid pointer to a screen, as returned by AK_Screen
  527.         w          - a valid pointer to a window, as returned by AK_Window
  528.  
  529.    RESULT
  530.  
  531.         -
  532.  
  533.    WARNING
  534.  
  535.         Well, the Display will be erased, so it has to be rewritten with
  536.         the new (or old) information.
  537.         The gadgets and the WindowFrame are both refreshed since V35.102.
  538.  
  539.    BUGS
  540.  
  541.         In former versions there have been some bugs.
  542.         Since V35.102 this function seems to be fully free of bugs.
  543.  
  544.    SEE ALSO
  545.  
  546.         "intuition.library", "graphics.library"
  547.  
  548. -----------------------------------------------------------------------------
  549.  
  550.    NAME
  551.  
  552.         AK_AutoRequester
  553.  
  554.    SYNOPSIS
  555.  
  556.         long AK_AutoRequester(struct Window *w, char *obertext, char *jatext,
  557.                               char *neintext)
  558.  
  559.    FUNCTION
  560.  
  561.         Opens an "AutoRequester", just like in "intuition.library" and gives
  562.         its result back.
  563.  
  564.    INPUT(S)
  565.  
  566.         w          - a valid pointer to a window, as returned by AK_Window
  567.         obertext   - a pointer to a null-terminated string (above text)
  568.         jatext     - a pointer to a null-terminated string (yes-text)
  569.         neintext   - a pointer to a null-terminated string (no-text)
  570.  
  571.    RESULT
  572.  
  573.         (l. "intuition.library", AutoRequest)
  574.  
  575.    WARNING
  576.  
  577.         "AutoRequest" uses IntuiTexts. "AK_AutoRequester" just uses strings.
  578.         This is the main difference you shouldn't forget.
  579.  
  580.    BUGS
  581.  
  582.         (l. "intuition.library", AutoRequest)
  583.  
  584.    SEE ALSO
  585.  
  586.         (l. "intuition.library", AutoRequest)
  587.  
  588. -----------------------------------------------------------------------------
  589.  
  590.    NAME
  591.  
  592.         AK_Alert
  593.  
  594.    SYNOPSIS
  595.  
  596.    long AK_Alert(char *text, long height)
  597.  
  598.    FUNCTION
  599.  
  600.         Displays an Alert at LeftEdge = 100 and TopEdge = 50 under use of the
  601.         "intuition.library" function "DisplayAlert".
  602.  
  603.    INPUT(S)
  604.  
  605.         text       -  a pointer to a null-terminated string (alert text)
  606.         height     - the Height of the alert-"screen"
  607.  
  608.    RESULT
  609.  
  610.         TRUE for LEFT-Button, FALSE for RIGHT-Button.
  611.         Always FALSE for DEADEND_ALERTS, but this functions only produces
  612.         RECOVERY_ALERTS.
  613.  
  614.         (l. "intuition.library", DisplayAlert)
  615.  
  616.    WARNING
  617.  
  618.         Be careful. DeadEnd-Alerts never come back.
  619.  
  620.         (l. "intuition.library", DisplayAlert)
  621.  
  622.    BUGS
  623.  
  624.         (l. "intuition.library", DisplayAlert)
  625.  
  626.    SEE ALSO
  627.  
  628.         (l. "intuition.library", DisplayAlert)
  629.  
  630. -----------------------------------------------------------------------------
  631.  
  632.    NAME
  633.  
  634.         AK_FileRequest
  635.  
  636.    SYNOPSIS
  637.  
  638.         char * AK_FileRequest(long xpos, long ypos, struct Screen *fscreen,
  639.                               struct Window *fwindow, long ftype)
  640.  
  641.    FUNCTION
  642.  
  643.         Opens the special "AK_GEN0"-Filerequester, which fully administrates
  644.         itself and just returns a pointer to a string.
  645.         Under OS >= V2.04 the "asl.library" is used for that.
  646.  
  647.    INPUT(S)
  648.  
  649.         x          - x-position for the requester-window
  650.         y          - y-position for the requester-window
  651.         fscreen    - a valid pointer to a screen, as returned by AK_Screen
  652.         fwindow    - a valid pointer to a window, as returned by AK_Window
  653.         ftype      - the Type of the Screen "fscreen" as used with
  654.                      "AK_Screen"
  655.  
  656.    RESULT
  657.  
  658.         A pointer to a null-terminated string (FilePath plus -Name).
  659.  
  660.    WARNING
  661.  
  662.         The String has to be given free after use. The length for this is
  663.         defined as "AK_FILEREQ_STRING_LEN" in the Headerfile "AK_GEN0.h".
  664.  
  665.    BUGS
  666.  
  667.         -
  668.  
  669.    SEE ALSO
  670.  
  671.         AK_ReadDir
  672.  
  673. -----------------------------------------------------------------------------
  674.  
  675.    NAME
  676.  
  677.         AK_ReadDir
  678.  
  679.    SYNOPSIS
  680.  
  681.         long AK_ReadDir(char *pathname, char **direntry, long *dirtype)
  682.  
  683.    FUNCTION
  684.  
  685.         This function is mainly used by "AK_FileRequest" to read the contentd
  686.         of directories.
  687.  
  688.    INPUT(S)
  689.  
  690.         pathname   - Path of directory to read
  691.         direntry   - the address of an array of at least 50 char-pointers,
  692.                      which all point to a separat 40-character-array (at least)
  693.         direntry   - an array of at least 50 (long) integers, which will be-
  694.                      come TRUE for directories and FALSE for files.
  695.                      (Other values, which are defined in the included file
  696.                       are _only_ for PRIVATE use inside the FileRequester.)
  697.  
  698.    RESULT
  699.  
  700.         The number of entries found and read.
  701.  
  702.    WARNING
  703.  
  704.         Don't forget to alloc and the free the arrays !!!
  705.  
  706.    BUGS
  707.  
  708.         -
  709.  
  710.    SEE ALSO
  711.  
  712.         AK_FileRequest
  713.  
  714. -----------------------------------------------------------------------------
  715.  
  716.    NAME
  717.  
  718.         AK_WaitKey
  719.  
  720.    SYNOPSIS
  721.  
  722.         void AK_WaitKey(long rawcode)
  723.  
  724.    FUNCTION
  725.  
  726.         This Function waits for a special (rawcode) key, but not in a multi-
  727.         tasking conform way (direct register access).
  728.  
  729.    INPUT(S)
  730.  
  731.         rawcode    - the RawKey-Code to wait for
  732.  
  733.    RESULT
  734.  
  735.         -
  736.  
  737.    WARNING
  738.  
  739.         Remember ! This is not multitasking-like ! (But its simple :)
  740.  
  741.    BUGS
  742.  
  743.         8)
  744.  
  745.    SEE ALSO
  746.  
  747.         Register : 0xBFEC01
  748.  
  749.            :>
  750.  
  751. -----------------------------------------------------------------------------
  752.  
  753.    NAME
  754.  
  755.         AK_WaitLeft
  756.  
  757.    SYNOPSIS
  758.  
  759.         void AK_WaitLeft(void)
  760.  
  761.    FUNCTION
  762.  
  763.         This Function waits for the left MouseButton, but not in a multi-
  764.         tasking conform way (direct register access).
  765.  
  766.    INPUT(S)
  767.  
  768.         -
  769.  
  770.    RESULT
  771.  
  772.         -
  773.  
  774.    WARNING
  775.  
  776.         Remember ! This is not multitasking-like ! (But its simple :)
  777.  
  778.    BUGS
  779.  
  780.         8)
  781.  
  782.    SEE ALSO
  783.  
  784.         Register : 0xBFE001
  785.  
  786.            :>
  787.  
  788. -----------------------------------------------------------------------------
  789.  
  790.    NAME
  791.  
  792.         AK_GetNum
  793.  
  794.    SYNOPSIS
  795.  
  796.         long AK_GetNum(long min, long max)
  797.  
  798.    FUNCTION
  799.  
  800.         Creates some kind of a random number ... :)
  801.  
  802.    INPUT(S)
  803.  
  804.         min        - the left border for number "X"
  805.         max        - the right border for number "X"
  806.  
  807.    RESULT
  808.  
  809.         number "X" itself.
  810.  
  811.    WARNING
  812.  
  813.         This function runs as long as it produces such number.
  814.  
  815.    BUGS
  816.  
  817.         -
  818.  
  819.    SEE ALSO
  820.  
  821.         -
  822.  
  823. -----------------------------------------------------------------------------
  824.